MACD 5 (Alt)/MACD 5.bin/workbench/wb/czesc_1/cwdemo/cwdemo.zoo/CWDemo.doc

Text File | 1989-11-08 | 25.5 KB | 539 lines

       Color Window Version 3.2 - CWDemo Documentation
  ______________________________________________________________

    Copyright (c) 1989  Kimbersoft, Surrey, BC, Canada


This software is protected by Canadian Copyright Law and by International
Treaty Provisions. Kimbersoft explicitly authorizes you to freely
distribute the program file CWDemo, the demo documentation file CWDemo.doc,
and the zoo file CWDemo.zoo; provided they are not altered in any way.

  Kimbersoft is a trademark of Kimbersoft, Ent.
  Amiga is a registered trademark of Commodore-Amiga, Inc.
  AmigaDOS is a trademark of Commodore-Amiga, Inc.
  Commodore is a registered trademark of Commodore Electronics Limited
  Intuition is a trademark of Commodore-Amiga, Inc.
  Workbench is a trademark of Commodore-Amiga, Inc.


    I    Color Window PREFACE

Color Window is a quality software product built to provide users of the
Commodore Amiga a preferred method of controlling the color register
assignments of Intuition custom screens. Color Window achieves this
objective by opening a control window on the active screen (henceforth
referred to as `The Color Window'). The Color Window can be opened on any
Intuition screen which is either low or high resolution, laced or
inter-laced, with either one, two, three, four or five bit planes; so long
as the machine can multi-task and there is enough memory.

The opening of The Color Window is controlled by the program CWHandler. The
code for this program monitors the console for a specific key sequence.
Once found, the event will be removed from the input chain and the program
CWindow will begin execution. CWHandler then returns to monitoring the
console. The CWindow code opens The Color Window upon the active screen
after having determined the characteristics of that screen.


    II    CWDemo vs Color Window

This Demonstration can be run from either the Workbench or the Shell. From
the Workbench open the CWDemo drawer and double click upon the CWDemo icon.
From the Shell enter the command `CWDemo/CWDemo'. There is a ten second
delay before The Color Window is opened to allow you to activate a window
upon the Intuition screen you wish The Color Window to open on.

Color Window Version 3.2 differs from this Demonstration Version in that
CWDemo does not support either an Initialization File or Data Files and The
Color Window cannot be opened from the console device. All other features
are the same.


    III    Color Window OPERATION

The intended operating environment is AmigaDOS Version 1.3 using either the
Amiga Shell or any shell which knows of the resident command list. The
program CWHandler is to be executing and the program CWindow is to be on
the resident command list. If the startup-sequence has not executed the
commands which perform this they can be entered from the Shell after Color
Window has been installed.

    resident SYS:c/CWindow
    SYS:CWHandler

Once this is done, The Color Window may be opened on the screen which
contains the active window by entering the right Amiga HELP key sequence
simultaneously on the console device.

The CWHandler code toggles program execution on and off when run. If the
handler is not active it will begin execution and if the handler is active
it will terminate execution. CWHandler can be run from either the Workbench
or the Shell.

The file SYS:CWData/CWindow.init is used by CWindow as an initialization
file to provide custom program features. These features are explained
further on in the documentation.

The Color Window can be opened any number of times upon the same screen.
You will find this usefull when you would like to use more than one of The
Color Window functions alternately. This feature also enables you to create
new Data Files (explained further on in the documentation). The Color
Window can also be opened on different screens concurrently.

Color Window operational errors and program notifications will be presented
within The Color Window via a requester. Whenever this requester is active
it must be acknowledged thru selection before continuing.


    IV    Color Window INSTALLATION

The execute script file CWindow.install will install Color Window on the
SYS: volume. You need only ensure that SYS: is assigned to the volume you
wish to contain Color Window. CWindow.install can be executed from either
the Workbench or the Shell.


    V    Color Window ORDERING INFORMATION

Product cost is $29.95 plus $5.00 shipping/handling/tax (Canadian Funds).

Payment can be made by either Mastercard, Visa, Money Order or Certified
Cheque.

For immediate service call our order line :    (604) 534 - 7098

Address mail orders to                 :     Kimbersoft
                            6020 Brooks Crescent
                         Surrey, BC  V3S 7L2
                        Canada


    1    The COLOR WINDOW

When CWindow execution begins, The Color Window will open and be activated
on the Intuition screen which contains the active window. Whenever The
Color Window is active, the pointer will be modified to a character string
significant to the program state. This string will be displayed with either
a solid or translucent background. A flag within the initialization file
initially determines which display mode will be used and can be toggled on
or off from the Options Requester.

    1.1    The COLOR WINDOW - Checkpoint and Restore

A major concern of The Color Window is in providing protection against
undesirable changes to the color values while they are being modified. This
is addressed by the CHECKPOINT and RESTORE gadgets. When the Checkpoint
Gadget is selected, a checkpoint base will be set containing the color
values of all the Color Gadgets. The checkpoint base will initially be set
to the Screen colors when The Color Window opens. The Restore Gadget will
restore the color values of all the Color Gadgets from the checkpoint base.
The restore can be undone by the Undo Faclity as explained below.

    1.2    The COLOR WINDOW - The Undo Facility

An Undo Facility is provided thru the use of the right mouse button. This
feature is quite dynamic and will behave according to what your last action
was. Explaination of the Undo Facility is provided throughout the
documentation wherever applicable.

    1.3    The COLOR WINDOW - The Color Gadgets

The Color Window contains a Color Gadget for each color register used by
the screen. These are located at the top of the window in row/column,
left/right order. The Color Window always maintains one of these Color
Gadgets as the Active Color and this will be represented with a larger
gadget image than the other Color Gadgets. Certain Color Window operations
will act upon the Active Color (as explained in the documentation).

    1.4    The COLOR WINDOW - The Slider Gadgets

There are three proportional Slider Gadgets located directly below the
Checkpoint/Restore Gadgets. These either represent the RGB or the HSL
values of the Active Color. Selection of the toggle gadget on the left of
the sliders alternates the representation mode. In RGB mode, the first
slider is for adjusting the red content in the Active Color and the second
is for the green content and the third is for the blue content. In HSL
mode, the first slider is for selecting the hue of the Active Color and the
second is for determining the saturation of that hue and the third is for
determining the luminance of that hue. All three Slider Gadget knobs will
be represented either as a solid box the same color as the Active Color or
as a rectangle filled with the window background color. A flag within the
initialization file initially determines which representation will be used
and can be toggled on or off from the Options Requester.

To use the Slider Gadgets you first select the Color Gadget you wish to
modify (making this the Active Color) and then either select the Slider
Gadget knob and move the pointer to the left or right while selected or
select the Slider Gadget container on the left or right of the knob. These
selections will either decrease or increase the component value in the
Active Color. The numerical RGB values are always displayed on the right
side of the sliders.

The Undo Facility will reset the component values of each Slider Gadget to
their last selected value. This feature can be used in experimenting with
the component values in the Active Color by first selecting the knob(s) of
the Slider Gadget(s) you do not wish to modify and then after modifying the
component value(s) desired, using the Undo Facility to switch the old and
new values back and forth.

    1.5    The COLOR WINDOW - The Toggle Gadgets

There are four Toggle Gadgets which when selected ON, modify the behaviour
of further Color Gadget selections. Only one of these can be ON at any one
time. Whenever one of the toggle gadgets is selected on, The Color Window
character string pointer will indicate this. To avoid any surprizes while
selecting Color Gadgets, it is good practice to check the pointer before
making the selection.

    1.5.1    The COLOR WINDOW - Randomize

If the RANDOMIZE gadget is ON when a Color Gadget is selected, random
values will be placed into that color registers red, green, and blue
component values. The select area for the RANDOMIZE toggle gadget is
within the border drawn inside the gadget's image. The area outside this
border has another purpose as explained in 1.6. The value randomizations
can be undone by the Undo Faclity.

    1.5.2    The COLOR WINDOW - Swap

If the SWAP gadget is ON, the values of the first selected Color Gadget
will be swapped with the values of the next Color Gadget selected. Once
the swap has occurred, another Color Gadget can be selected as the first
selected and so on until the SWAP gadget is turned OFF. If you lose track
of which is which, turn the SWAP gadget OFF and ON to start fresh. The
swap can be undone by the Undo Facility.

    1.5.3    The COLOR WINDOW - Copy

If the COPY gadget is ON, the values of the first selected Color Gadget
will be copied to the values of the next Color Gadget selected. Once
the COPY has occurred, another Color Gadget can be selected as the first
selected and so on until the COPY gadget is turned OFF. If you lose track
of which is which, turn the COPY gadget OFF and ON to start fresh. The copy
can be undone by the Undo Facility.

    1.5.4    The COLOR WINDOW - Move

If the MOVE gadget is ON, the values of the first Color Gadget selected
will be moved to the values of the next Color gadget selected and the
values of all the Color Gadget's between the two will be shifted either to
the left or to the right depending upon whether the positional value of the
first Color Gadget selected is less than or greater than the second Color
Gadget selected. Once the move has occurred, another Color Gadget can be
selected as the first selected and so on until the MOVE gadget is turned
OFF. If you lose track of which is which, turn the MOVE gadget OFF and ON
to start fresh. The move can be undone by the Undo Facility.

    1.6    The COLOR WINDOW - Global Randomization

The Randomize Gadget also has a global select area located within the
gadget select box outside the border displayed in this gadget. Random
values will be placed into ALL color register component values when a
selection is made within this area. The Randomize Toggle Gadget and the
Randomize Global Select Area operate independantly of one another. The Undo
Facility will restore all the color values to their previous values.

    1.7    The COLOR WINDOW - Cycle

The CYCLE gadget will shift all of the color values either to the left or
to the right depending on whether the left side or the right side of the
gadget was selected. The shifting will continue until the gadget selection
is released. The last cycle can be undone by the Undo Facility.

    1.8    The COLOR WINDOW - Sets

The SETS gadget activates the Data Requester in Sets Mode. Among other
operations, this enables you to initialize ALL colors from a file of stored
color values. Full explaination is provided in the Data Requester section.

    1.9    The COLOR WINDOW - Colors

The COLORS gadget activates the Data Requester in Colors Mode. Among other
operations, this enables you to initialize ONLY the Active Color from a
file of stored color values. Full explaination is provided in the Data
Requester section.

    1.10    The COLOR WINDOW - Reference

The REFERENCE gadget activates the Reference Window. The current Refernce
File will be displayed within a new window opened upon the same screen that
The Color Window is on. Full explaination is provided in the Reference
Window section.

    1.11    The COLOR WINDOW - Options

The OPTIONS gadget activates the Options Requester. This requester allows
you to determine which Data File Names and which Reference File Name will
be used by Color Window. The state of the Character String Pointer and the
Slider Gadget Knobs can also be determined in this requester. Full
explaination is provided in the Options Requester section.

    1.12    The COLOR WINDOW - Quit

The QUIT gadget will close The Color Window and terminate CWindow program
execution. There is really nothing you need worry about before The Color
Window closes so you are not asked for confirmation.


    2    The DATA REQUESTER

The primary objective of The Color Window is to provide you with the
ability to save and initialize either all of the color values or the value
of an indivdual color. This was accomplished by incorporating the Data
Requester and by using Data Files.

Whenever The Data Requester is active, the pointer will be modified to a
character string significant to the program state. This string will be
displayed in the same way as The Color Window's string pointer. To avoid
any surprizes while operating upon the Data File, it is a good habit to
check the pointer before making any selections.

    2.1    The DATA REQUESTER - Data Modes

The Data Requester will either be in Sets Mode or Colors Mode depending on
whether the Sets Gadget or the Colors Gadget activated the requester. In
Sets Mode the requesters will operate upon the data items contained within
the Sets Data File and in Colors Mode upon the data items contained within
the Colors Data File. The Color Window initialization file initially
determines which Data File will be used. You can either select a different
Data File or request that a new Data File be created by activating the
Options Requester and modifying the Data File Name before activating the
Data Requester. New and modified data items will not be written to the Data
File until the Quit Gadget is selected. Only when the Data Requester is in
Colors Mode can The Color Window Color Gadgets be selected in determining
the Active Color.

    2.2    The DATA REQUESTER - Data Files

A Sets Data File contains thirty-two color values and a character string up
to seventeen characters in length for each data item within the Data File.
A Colors Data File contains a single color value and a character string
also up to seventeen characters in length for each data item within the
Data File. Any data item in either a Sets Data File or a Colors Data File
can be used by any Color Window at any time.

There is no limit to the number of Data Files which can exist. Each Data
File is however, restricted to one hundred data items. Color Window is
shipped with one Sets Data File containing sixty data items and one Colors
Data File containing sixty colors.

    2.3    The DATA REQUESTER - The Data String Gadgets

The data item character strings will be displayed in Data String Gadgets
prefixed with their ordinal position amongst the data items available. The
data items can be identified by any character string you wish by activating
the Data String Gadget and entering the string upon the console device.

    2.4    The DATA REQUESTER - The Box Gadgets

The Box Gadgets adjacent the Data String Gadgets are for selecting the data
item to act upon. If none of the Toggle Gadgets are ON when a Box Gadget is
selected, either all of the colors will be initialized or only the Active
Color, depending on whether the Data Requester is in Sets Mode or Colors
Mode. The initialization can be undone by the Undo Facility explained in
section 1 subsection 2. The action taken when one of the Toggle Gadgets is
ON is determined by the definition of that Toggle Gadget as described
below.

    2.5    The DATA REQUESTER - The Scrolling Gadgets

The Slider Gadget and the Arrow Gadgets located to the left of the Box
Gadgets are for determining which data items will be available for Data
Requester operations. The position and size of the Slider Gadget's knob
will reflect the location and proportion of the displayed data items to
the available data items. The data items are scrolled either backward or
forward by either selecting the Slider Gadget's knob and moving the mouse
up or down while selected or by selecting either Arrow Gadget. The Arrow
Gadgets will scroll the data items as long as the gadget is selected. You
can also either decrease or increase the first data item displayed by seven
items by making a selection inside the Slider Gadget's container either
above or below the Slider Gadget's knob.

    2.6    The DATA REQUESTER - Checkpoint and Restore

The CKPT gadget will set a checkpoint base containing all of the data item
values and strings at the time of selection. The checkpoint base will
initially be set to the Data File contents whenever the Data Requester is
activated. The RESTORE gadget will restore all of the data item values and
strings from the checkpoint base.

    2.7    The DATA REQUESTER - The Toggle Gadgets

There are three Toggle Gadgets which when selected ON modify the behaviour
of Box Gadget selections. Only one of these gadgets can be ON at any one
time. Whenever one of the toggle gadgets is selected on, The Color Window
character string pointer will indicate this. To avoid any surprizes while
selecting Box Gadgets, it is a good habit to check the pointer before
making the selection.

    2.7.1    The DATA REQUESTER - Delete

If the DELETE gadget is ON, the data item associated with the Box Gadget
will be removed. You will not be asked for confirmation. Either use the
CKPT/Restore feature or select the Abort Gadget if undesirable deletions
have been made.

    2.7.2    The DATA REQUESTER - Move

If the MOVE gadget is ON, the first data item selected by a Box Gadget will
be moved to the location of the data item associated with the next Box
Gadget selected. Once the MOVE has occurred, another Box Gadget can be
selected as the first selected and so on until the Move Gadget is turned
OFF. The character string pointer will either indicate that the Move Gadget
is ON or indicate the data item which is to be moved.

    2.7.3    The DATA REQUESTER - Save

If the SAVE gadget is ON, either all of the color values or the value of
the Active Color will be saved at the data item location associated with
the Box Gadget selected, depending on whether the Data Requester is in Sets
Mode or Colors Mode. When a Save operation is performed on a Sets Data File
only the data items associated with the active screen are modified. This
preserves any color values not used by the active screen so that screens
with more bit planes can initialize the data item values as previously set.

    2.8    The DATA REQUESTER - The Insert Gadgets

Six Insert Gadgets will appear to the right of the Box Gadgets whenever the
Save Gadget is selected ON. The selection of these gadgets will insert a
new data item after the data item associated with the Box Gadget above the
selected Insert Gadget. After the data item has been inserted, the Data
String Gadget associated with that data item will be activated. You can
either enter a character string from the console or ignore the activation.
If you choose to ignore the activation, the character string associated
with that data item will be a question mark.

    2.9    The DATA REQUESTER - Quit

The QUIT gadget will first activate the Options Requester and then (once
the Options Requester is terminated) update the Data File and terminate the
Data Requester. The Options Requester is activated to allow you to specify
which Data File to update. This feature is provided for when you do not
wish to alter the original Data File and for archiving purposes.

    2.10    The DATA REQUESTER - Abort

The ABORT gadget will terminate the Data Requester without updating the
Data File. This is the preferred way to terminate the Data Requester if no
modifications have been performed or the data has been modified to an
undesirable state and the chekpoint base is also undesirable.


    3    The REFERENCE WINDOW

The Reference Window is a text file viewer provided primarily for use in
referencing The Color Window documentation though a different file can be
specified by activating the Options Requester and modifying the Reference
File string gadget before the Reference Window is activated. The Reference
Window will be activated initially displaying the file whose name is
contained within Color Window's initialization file whenever the Reference
Gadget in The Color Window is selected. The current version of Color Window
is limited to displaying at most one thousand lines of text.

    3.1    The REFERENCE WINDOW - Display Modes

The Reference File will be displayed in either Autoscroll Mode or Manual
Mode within a new window opened upon the same screen that The Color Window
is on. The display mode will be indicated by the pointer whenever the
Reference Window is active. Initially, the Reference Window will open in
Autoscroll Mode. After openining the window, there is a five second delay
before any operations are performed.

    3.2    The REFERENCE WINDOW - The Autoscroll Gadgets

Located down the right side of the window there are five gadgets for
controlling the display. The Autoscroll Gadgets, located directly above
and below the Slider Gadget, control the display mode. When neither of the
Autoscroll Gadgets are selected ON, the display will be in Manual Mode.
When the Autoscroll Gadget at the top of the Reference Window is selected
ON, the display will scroll backwards in the Reference File whereas when
the Autoscroll Gadget at the bottom of the Reference Window is selected ON,
the display will scroll forwards in the Reference File.

    3.3    The REFERENCE WINDOW - The Slider Gadget

In Autoscroll Mode the Slider Gadget's knob represents the scrolling rate.
To increase or decrease the scrolling rate either select the Slider
Gadget's knob and move the mouse up or down while selected or make a
selection within the Slider Gadget's container either above or below the
Slider Gadgets's knob.

In Manual Mode the Slider Gadget's knob represents the display position and
proportional amount of the Reference File being displayed. To move backward
or forward in the file either select the Slider Gadget's knob and move the
mouse up or down while selected or make a selection within the Slider
Gadget's container either above or below the Slider Gadgets's knob.

    3.4    The REFERENCE WINDOW - The Arrow Gadgets

The Arrow Gadgets located directly above and below the Autoscroll Gadgets
will scroll the display at the highest rate either backwards or forwards
depending on whether the Arrow Gadget at the top or bottom of the window
is selected. The scrolling will continue until the selection is released.
The Arrow Gadgets can be selected when the display is either in Autoscroll
Mode or Manual Mode.


    4    The OPTIONS REQUESTER

The Options Requester is provided to enable you to customize The Color
Window environment as well as enhance the capacity of the Data Requester.
The Options Requester will be activated whenever the Options Gadget in The
Color Window is selected and whenever the Quit Gadget in the Data Requester
is selected. The information that the Options Requester initially displays
is obtained from Color Window's initialization file.

    4.1    The OPTIONS REQUESTER - Reference File

The REFERENCE FILE string gadget controls which text file will be displayed
when the Reference Gadget in The Color Window is selected.

    4.2    The OPTIONS REQUESTER - Sets File

The SETS FILE string gadget controls which Data File will be used when the
Sets Gadget in The Color Window is selected and which Data File will be
updated when the Quit Gadget in the Data Requester is selected (if the
Data Requester was activated from The Color Window Sets Gadget).

    4.3    The OPTIONS REQUESTER - Colors File

The COLORS FILE string gadget controls which Data File will be used when
the Colors Gadget in The Color Window is selected and which Data File will
be updated when the Quit Gadget in the Data Requester is selected (if the
Data Requester was activated from The Color Window Colors Gadget).

    4.4    The OPTIONS REQUESTER - Pointer

The POINTER toggle gadget controls whether The Color Window pointer will be
displayed as a character string with a solid background or as a character
string with a translucent background; depending on whether the gadget is ON
or OFF.

    4.5    The OPTIONS REQUESTER - Knobs

The KNOBS toggle gadget controls whether The Color Window Slider Gadget
knobs will be displayed as a rectangle filled with the screen background
color or as a solid box the same color as the Active Color; depending on
whether the gadget is ON or OFF.

    4.6    The OPTIONS REQUESTER - Update

The UPDATE toggle gadget determines whether or not the Color Window
initialization file is to be updated. Only when the Update Gadget is
selected ON is the initialization file flagged for updating (the file
update is not performed until the Quit Gadget is selected). The Update
Gadget is initially selected OFF when The Color Window is opened.

    4.7    The OPTIONS REQUESTER - Okay

The OKAY gadget will first update the initialization file (ONLY if the
Update Gadget is selected ON) and then terminate the Options Requester.


                The End
  ______________________________________________________________

   Kimbersoft - Color Window Version 3.2 - CWDemo Documentation